GrADS Coordinates Systems --

World, Grid and Plot Coordinates

		   The GrADS World Coordinate

			  Mike Fiorino

     Program for Climate Model Diagnosis and Intercomparison
	     Lawrence Livermore National Laboratory
		    University of California
		       P.O. Box 808 L-264
		       Livermore, CA 94551
	     510-423-8505 (voice) 510-422-7675(fax)Hi!



			7 March, 1996


1)	INTRODUCTION

I believe the most significant contribution of GrADS to the data
"slicing" problem is its support of a universal,
EXTERNAL-TO-THE-DATA "world coordinate."  

There are three coordinate systems in GrADS:

*	GRID or index coorindate where data are reference by indices
*	WORLD or some external physical coordinate
*	PLOT or x-y location on the screen

We'll first concentrate on the data cooridinates GRID and WORLD
before discussing PLOT coordinates since these are the most
important for data display and analysis.

The world coordinate is 4-D and is DEFINED INSIDE GrADS as the
variables or dimensions with the names "lon", "lat", "lev" and
"time".  The typical correspondence between these GrADS world
coordinates and the "real world" is:

lon 	=	longitude on the earth in degrees east
lat	=	latitude on the earth in degrees N
lev	=	pressure levels, sigma levels or theta levels
time	=	REAL TIME in min, hours, days, months and years (Gregorian calendar)

For example, the point in the physical world (NOT DATA) of
(14.3N; 145E; 500 mb; 00:12 UTC on 7 March 1996 (a point above
Guam)) in GrADS world coordinates (lon;lat;lev;time) would be
(14.3;145.0;500;12:00Z7Mar1996).

The grid coordinate is also 4-D and is DEFINED INSIDE GrADS as
("x","y","z","t").  In FORTRAN, the data would written out

parameter (nx=144,ny=73,nz=17,nt=2)
dimension u(nx,ny,nz,nt)
integer x,y,z,t

do t=1,nt	  
  do z=1,nz
    write(10) ((u(x,y),x=1,nx),y=1,ny)
  end do
end do


In GrADS, one can REFERENCE data in the GrADS world coordinate
IRRESPECTIVE of the underlying data structure.  This feature is
something that the netCDF data access procedures do NOT support
and is what makes GrADS a powerful data slicer.

However, as in the real world, GrADS only supports ONE
relationship or "map" between world and grid coordinates at a
time.  This map is based on the "default" file which by default
is the first file opened.  To understand where this world->grid
and grid->world map comes from consider the following data
descriptor or .ctl file:

dset ^bm.dat
title the best model ver data 
options yrev zrev
xdef 72 linear 0.0 5.0
ydef 46 linear -90 4.0
zdef  3 levels 850 500 200
tdef  1 linear 00z1jan1996 12hr
vars 1
z 3 0 geopotential height
endvars

the map is defined by the "x(y,z,t)def" cards and (optionally)
the "options" card.  In GrADS the world coordinate is ALWAYS
defined such that longitude ("lon") increases from West to East,
latitutde ("lat") increases toward the North and pressure level
("lev") DECREASES with height (this is not strictly true but is
very important when doing calculations such as vint). Time is a
special case and can ONLY be linear with equal spacing (12 hr in
the example).  While the ?def "cards" can be ordered in any way
in th .ctl file, the world coordinate inside GrADS is ALWAYS
(lon,lat,lev,time).  However, this does NOT mean the DATA has be
arranged this way and the "options" card tells GrADS how the data
differs from the standard.  In the above example case, the
latitudes in GRID cooridates DECREASES with INCREASING y, that is
y=1 -> lat=90; y=2 -> lat=86; y=45 -> lat=-90 (some models and
graphics systems prefer this orientation).  Similarly, lev=200 is
stored first, followed by lev=500 and lev=200.  Other
modifications to the world<->grid map are possible, as described
in the full document.

2)	      


2)	DISPLAYING DATA RELATIVE TO THE WORLD COORDINATE

The first task in intercomparing two or more data sets with
different grids (i.e., different grid and world coordinates or
grid-world "maps") is the graphical overlay or plotting two
fields on top of each other.  One specifies a 0-3 dimensional
volume in either grid or world coordinates and then "display" a
variable.  Consider the typical case of a 2-D contour plot:

'open psl.ecmwf.ctl'
'open psl.ncep.ctl'
'set gxout contour'
'set t 1'
'set lon 0 180'
'set lat 0 90'
'd psl'

and let's see what is happening inside GrADS.

the "default" file is the first one or the data in psl.ecmwf.ctl.
This specifes that the grid-world and world-grid map will be
based on the psl.ecmwf.ctl.

'set t 1' - look at the first time in the file or we could of

'set time 00z1mar96' if that were the actual time corresponding the